---
title: Feat 文档写作标准
description: 为确保 Feat 文档的一致性、专业性和易读性而制定的写作标准。所有参与 Feat 文档编写的 AI 应遵循这些准则，以产出符合项目要求的高质量文档。
---

## 关于文档

本文档为 Feat 框架的文档写作标准指南。它提供了文档结构、写作风格和技术内容呈现等方面的指导原则。

所有 Feat 文档均为开源内容。如果您发现文档存在问题或希望改进文档，请积极参与贡献。

### 文档编写理念

Feat 文档采用"实践为主，原理为辅"的编写理念，优先介绍功能的实际应用，然后根据需要解释相关的技术原理。这种编写方式有助于读者快速上手并解决实际问题。

### 获取帮助

如果在编写 Feat 文档时遇到问题，可通过以下方式获取帮助：

- 参考本文档获取写作指导
- 查阅 Feat 官方示例文档
- 在[项目讨论](https://gitee.com/smartboot/feat/issues)区提问

## 1. 入门指南

如果您刚开始接触 Feat 文档编写，请从以下几个方面入手：

- 了解文档的基本结构和格式要求
- 熟悉技术内容的表达方式
- 学习代码示例和图表的使用规范

### 1.1 文档目标

本文档旨在：

- 统一 Feat 项目文档的写作风格
- 提升文档的专业性和可读性
- 确保文档内容的质量和一致性
- 为 AI 辅助文档编写提供明确指导
- 强调功能实践，辅以原理解析的写作方法

## 2. 文档结构标准

### 2.1 文档头部信息

每篇文档必须包含标准的头部信息（Frontmatter）：

```md
---
title: 文档标题
description: 简短描述文档内容
sidebar:
  order: 排序数字（可选）
---
```

### 2.2 标题层级

- 由于已存在文章title，无需使用 `#` 表示主标题（H1）
- 使用 `##` 表示章节标题（H2）
- 使用 `###` 表示小节标题（H3）
- 最多使用三级标题，避免更深的嵌套

### 2.3 内容组织原则

1. **实践优先**：优先介绍如何使用功能，提供实际可用的示例
2. **原理补充**：在读者了解基本用法后，适当解释背后的原理
3. **循序渐进**：从基础功能开始，逐步深入高级特性
4. **实例驱动**：通过具体示例演示功能的使用方法

## 3. 语言风格标准

### 3.1 语气与语调

- **专业而不晦涩**：使用准确的技术术语，但避免过度复杂的表达
- **客观且友好**：保持中立态度，同时体现人文关怀
- **简洁明了**：用最少的文字传达最多的信息

### 3.2 表达规范

- 使用主动语态，避免被动语态
- 使用现在时态描述一般情况
- 保持句子结构简单，避免过长的复合句

### 3.3 词汇选择

- 使用统一的专业术语（如："Feat"而非"feat"）
- 避免口语化表达
- 优先使用具体而非抽象的词汇

## 4. 技术内容标准

### 4.1 代码示例规范

- 每段代码示例必须配有简要说明，重点说明用途和使用方法
- 重要的代码行应添加注释，特别是关键参数和配置项
- 示例代码应具备完整性和可执行性
- **突出实践**：优先展示功能的具体应用场景，而非理论框架
- **简化示例**：仅展示与当前讨论主题相关的核心代码，避免冗长的样板代码
- 使用适当的语法高亮标记
- **代码验证**：所有代码示例必须基于项目实际源码，确保与项目实际情况完全一致，不得出现任何虚构或不正确的代码片段

```java
// 实践导向的示例：展示如何创建HTTP服务
public class HttpServerExample {
    public static void main(String[] args) {
        // 创建HTTP服务器并监听8081端口
        Feat.httpServer()
                .httpHandler(request -> {
                    // 处理HTTP请求，返回"Hello World"响应
                    request.getResponse().write("Hello World");
                })
                .listen(8081);
    }
}
// 注：省略了不影响理解的样板代码
```

所有代码示例都应该链接到 Gitee 仓库中的实际文件，以便读者可以查看完整的上下文和运行示例。例如：

有关完整示例，请参见 [HelloWorld.java](https://gitee.com/smartboot/feat/blob/master/feat-test/src/main/java/tech/smartboot/feat/demo/HelloWorld.java)

:::note
如果文档中的代码示例需要提供完整可运行的代码，应当在文档中添加指向 Gitee 仓库中实际文件的链接，方便读者查找和运行完整示例。
代码统一存放在：https://gitee.com/smartboot/feat/blob/master/feat-test/src/main/java/tech/smartboot/feat/docs/ 目录下。
:::

:::caution
强制要求：所有文档中的代码示例必须经过严格验证，确保与项目实际代码保持完全一致。AI在编写文档时必须参考项目真实存在的源码文件，禁止生成任何虚构或不正确的代码。所有链接必须指向 Gitee 仓库。
:::

### 4.2 功能实践与原理解析

在文档编写过程中，应按照以下方式平衡功能实践和原理解析：

1. **实践优先原则**：
   - 首先介绍功能的作用和使用场景
   - 提供可直接运行的代码示例
   - 说明常见配置选项及其效果

2. **原理补充原则**：
   - 在读者掌握基本用法后，适时解释工作原理
   - 通过图表等方式直观展示内部机制
   - 避免一开始就陷入复杂的理论讲解

3. **层次化内容组织**：
   - 基础用法部分：专注于"怎么做"
   - 进阶用法部分：解释"为什么这样做"
   - 工作原理解析：深入探讨"它是如何工作的"

### 4.3 图表使用规范

- **首选 Mermaid**：对于流程图、架构图等，优先使用 Mermaid 语法
- **复杂图表使用通道图**：对于复杂的系统交互图、数据流图等，优先使用通道图进行表达
- **SVG 备选方案**：当 Mermaid 和通道图无法满足需求时，可使用 SVG 格式并保存到 img 目录
- 图表应有明确的标题和说明文字
- 图片文件应存储在相应的 img 目录中
- 使用相对路径引用图片
- 使用 Mermaid 时，必须在文档顶部导入自定义组件：`import Mermaid from '../../../components/Mermaid.astro';`

#### Mermaid 图表规范

为了生成高质量的 Mermaid 图表，请遵循以下规范：

1. **图表结构要求**：
   - 使用清晰的节点命名，避免使用无意义的字母
   - 节点文本应简洁明了，不超过一行
   - 连接线应有明确含义，必要时添加标签
   - 保持图表布局整洁，避免线条交叉

2. **图表类型选择**：
   - 流程图：`graph TD` 或 `graph LR` 用于表示执行流程
   - 序列图：`sequenceDiagram` 用于表示对象间交互
   - 类图：`classDiagram` 用于表示类关系
   - 状态图：`stateDiagram` 用于表示状态变化
   - 组件图：`graph TD` 用于表示系统组件关系

3. **节点样式规范**：
   - 方形节点：`A[节点文本]`
   - 圆形节点：`A((节点文本))`
   - 菱形节点：`A{条件判断}`
   - 圆角矩形：`A(节点文本)`

4. **图表设计原则**：
   - **一致性**：同一文档中相同类型的元素应使用相同的样式
   - **可读性**：确保节点文本清晰可见，避免过长文本
   - **逻辑性**：图表流向应符合常规阅读习惯（从上到下或从左到右）
   - **简洁性**：只包含必要的信息，避免图表过于复杂

5. **高质量示例**：

流程图示例：
```jsx
<Mermaid code={`
graph TD
    A[用户请求] --> B{身份验证}
    B -->|验证成功| C[处理请求]
    B -->|验证失败| D[返回错误]
    C --> E[返回结果]
    D --> E
`} />
```

序列图示例：
```jsx
<Mermaid code={`
sequenceDiagram
    participant U as 用户
    participant S as 服务器
    participant D as 数据库
    
    U->>S: 登录请求
    S->>D: 验证凭据
    D-->>S: 验证结果
    S-->>U: 登录响应
`} />
```

类图示例：
```jsx
<Mermaid code={`
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    
    class Dog {
        +String breed
        +bark()
    }
    
    class Cat {
        +String color
        +meow()
    }
    
    Animal <|-- Dog
    Animal <|-- Cat
`} />
```

组件图示例：
```jsx
<Mermaid code={`
graph TD
    A[客户端] --> B(负载均衡器)
    B --> C[Web服务器1]
    B --> D[Web服务器2]
    B --> E[Web服务器3]
    C --> F[(数据库)]
    D --> F
    E --> F
`} />
```

在使用 Mermaid 图表之前，需要在文档顶部导入自定义的 Mermaid 组件：

```md
import Mermaid from '../../../components/Mermaid.astro';
```

然后在文档正文中使用 Mermaid 组件：

```jsx
<Mermaid code={`
graph TD
    A[开始] --> B[处理]
    B --> C[结束]
`} />
```

#### 通道图使用规范

对于复杂的系统架构图、数据流图等，应优先考虑使用通道图（Channel Diagram）：

1. **适用场景**：
   - 复杂的系统交互图
   - 多组件数据流图
   - 高并发处理流程图
   - 网络通信架构图

2. **设计原则**：
   - 清晰表达数据流向和处理节点
   - 合理划分通道和处理单元
   - 保持整体结构简洁易懂

3. **示例**：
```jsx
<Mermaid code={`
graph LR
    A[数据源] --> B{通道1}
    B --> C[处理器1]
    C --> D{通道2}
    D --> E[处理器2]
    E --> F[结果输出]
`} />
```

#### SVG 图表示例

对于复杂或特殊要求的图表，使用 SVG 格式：

```html
<img src="./img/example.svg" alt="示例图表" width="100%"/>
```

## 5. 格式排版标准

### 5.1 强调样式

- **加粗**：用于强调关键词或重要概念
- *斜体*：用于首次提及的术语或书籍名称
- `代码`：用于行内代码或命令

### 5.2 列表使用

- 有序列表用于步骤说明
- 无序列表用于列举要点
- 列表项应保持平行结构

### 5.3 表格规范

- 表头使用简洁明确的标签
- 表格内容应左对齐
- 表格前后应有说明文字

## 6. 特殊内容处理

### 6.1 注意事项与警告

对于需要特别提醒的内容，使用专门的提示框：

:::note
这是一般性提示信息
:::

:::caution
这是需要注意的警告信息
:::

:::tip
这是技巧或建议信息
:::

:::danger
这是危险或重要警告信息
:::

### 6.2 版本兼容性说明

涉及版本差异的内容应明确标注适用版本范围

### 6.3 性能与安全建议

提供性能优化建议和安全注意事项

## 7. 文档编写最佳实践

### 7.1 内容组织

- 每个文档应该有一个明确的中心主题
- 从最常用或最重要的信息开始
- 按照逻辑顺序组织内容

### 7.2 技术深度

- 优先提供功能使用的详细说明和实践指导
- 适度解释技术原理，帮助用户更好地理解和使用功能
- 避免过多底层实现细节影响用户快速上手
- 对于复杂主题，提供进一步阅读的链接

### 7.3 实用性

- 提供可操作的示例和指南
- 解决常见的使用问题
- 包含故障排除内容

## 8. AI 写作指导原则

### 8.1 内容准确性

- 确保功能使用说明的准确性
- 基于 Feat 项目实际情况进行描述
- 优先验证实践示例的正确性
- 避免推测性内容
- 所有代码示例必须与项目实际源码保持一致，禁止虚构代码

### 8.2 写作规范

- 严格遵循本文档规定的格式和风格
- 保持语言表达的一致性
- 确保文档结构清晰

### 8.3 上下文理解

- 准确理解用户查询意图，重点关注功能使用需求
- 结合 Feat 框架特点进行阐述，突出实用性
- 考虑目标读者的技术水平，提供合适的实践指导

## 9. 文档质量检查清单

在完成文档编写后，请对照以下清单进行检查：

- [ ] 标题是否准确反映内容主旨
- [ ] 是否优先介绍了功能的使用方法
- [ ] 是否提供了实际可用的代码示例
- [ ] 是否在适当时机解释了相关原理
- [ ] 代码示例是否完整且可运行
- [ ] 代码示例是否与项目实际源码一致
- [ ] 是否引用了实际存在的源码文件
- [ ] 是否存在错别字或语法错误
- [ ] 链接是否有效且指向 Gitee 仓库
- [ ] 图片是否正常显示
- [ ] 内容是否有逻辑错误或表述不清之处
- [ ] 是否符合整体文档风格
- [ ] 是否遵循了所有格式和结构标准
- [ ] 各章节是否逻辑清晰、粒度适中

通过遵循以上标准，AI 编写的 Feat 文档将更加专业、一致且易于理解，有助于提升整个项目的文档质量和用户体验。